<?xml version="1.0"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <title>Extremely Low-Level Socket Operations</title>
  </head>

  <body>
    <h1>Extremely Low-Level Socket Operations</h1>

    <h2>Introduction</h2>

    <p>
      Beyond supporting streams of data (SOCK_STREAM) or datagrams (SOCK_DGRAM),
      POSIX sockets have additional features not accessible via send(2) and
      recv(2).  These features include things like scatter/gather I/O,
      duplicating file descriptors into other processes, and accessing
      out-of-band data.
    </p>

    <p>
      Twisted includes a wrapper around the two C APIs which make these things
      possible,
      <a href="http://www.opengroup.org/onlinepubs/007908799/xns/sendmsg.html">sendmsg</a>
      and
      <a href="http://www.opengroup.org/onlinepubs/007908799/xns/recvmsg.html">recvmsg</a>.
      This document covers their usage.  It is intended for Twisted maintainers.
      Application developers looking for this functionality should look for the
      high-level APIs Twisted provides on top of these wrappers.
    </p>

    <h3>sendmsg</h3>

    <p>
      <code>sendmsg(2)</code> exposes nearly all sender-side functionality of a
      socket.  For a SOCK_STREAM socket, it can send bytes that become part of
      the stream of data being carried over the connection.  For a SOCK_DGRAM
      socket, it can send bytes that become datagrams sent from the socket.  It
      can send data from multiple memory locations (gather I/O).  Over AF_UNIX
      sockets, it can copy file descriptors into whichever process is receiving
      on the other side.  The wrapper included in Twisted,
      <code class="API" base="twisted.python.sendmsg">send1msg</code>, exposes
      many (but not all) of these features.  This document covers the usage of
      the features it does expose.  The alternate spelling for the wrapper is
      used to indicate the primary limitation, which is it that the interface
      supports sending only one <em>iovec</em> at a time.
    </p>

    <h3>recvmsg</h3>

    <p>
      Likewise, <code>recvmsg(2)</code> exposes nearly all the receiver-side
      functionality of a socket.  It can receive stream data over from a
      SOCK_STREAM socket or datagrams from a SOCK_DGRAM socket. It can receive
      that data into multiple memory locations (scatter I/O), and it can receive
      those copied file descriptors.  The wrapper included in
      Twisted, <code class="API" base="twisted.python.sendmsg">recv1msg</code>,
      exposes many (but not all) of these features.  This document covers the
      usage of the features it does expose.  The alternate spelling for the
      wrapper is used to indicate the primary limitation, which is that the
      interface supports receiving only one <em>iovec</em> at a time.
    </p>

    <h2>Sending And Receiving Regular Data</h2>

    <p>
      sendmsg can be used in a way which makes it equivalent to using the send
      call.  The first argument to sendmsg is (in this case and all others) a
      file descriptor over which to send the data.  The second argument is a
      string giving the data to send.
    </p>

    <p>
      On the other end, recvmsg can be used to replace a recv call.  The first
      argument to recvmsg is (again, in all cases) a file descriptor over which
      to receive the data.  The second argument is an integer giving the maximum
      number of data to receive.
    </p>

    <a class="py-listing" href="listings/sendmsg/send_replacement.py" />

    <h2>Copying File Descriptors</h2>

    <p>
      Used with an AF_UNIX socket, sendmsg send a copy of a file descriptor into
      whatever process is receiving on the other end of the socket.  This is
      done using the ancillary data argument.  Ancillary data consists of a list
      of three-tuples.  A three-tuple constructed with SOL_SOCKET, SCM_RIGHTS,
      and a platform-endian packed file descriptor number will copy that file
      descriptor.
    </p>

    <p>
      File descriptors copied this way must be received using a recvmsg call.
      No special arguments are required to receive these descriptors.  They will
      appear, encoded as a native-order string, in the ancillary data list
      returned by recvmsg.
    </p>

    <a class="py-listing" href="listings/sendmsg/copy_descriptor.py" />

  </body>
</html>
